package org.ranch.api.service;

import java.util.List;

import org.ranch.model.Permission;
import org.ranch.model.Role;
import org.ranch.model.User;
import org.ranch.model.exception.RanchOperationFailedException;
import org.ranch.model.exception.RanchValidationException;

/**
 * This interface contain the basic CRUD operations for a user
 */
public interface UserService {

    /**
     * gets a user based on their username
     * 
     * @param username
     *            string for login name
     * @return User or null if no much found
     */
    User findUserByUsername(String username);

    /**
     * saves a given user
     * 
     * @param user
     * @throws MohrValidationException
     *             thrown when the validation of the user fails.
     */
    void saveUser(User user) throws RanchValidationException;

    /**
     * gets a list of all users in the system
     * 
     * @return
     */
    List<User> getUsers();

    /**
     * deletes a given user from the system
     * 
     * @param user
     * @throws RanchOperationFailedException 
     * @throws MohrOperationFailedException
     *             thrown when the delete operation fails
     */
    void deleteUser(User user) throws RanchValidationException, RanchOperationFailedException;

    /**
     * saves a given role
     * 
     * @param role
     * @throws MohrValidationException
     *             thrown when the validation of the user fails.
     */
    void saveRole(Role role) throws RanchValidationException;

    /**
     * gets a list of all
     * 
     * @return
     */
    List<Role> getRoles();

    /**
     * deletes a given role from the system
     * 
     * @param role
     * @throws MohrOperationFailedException
     *             thrown when the delete operation fails.
     */
    void deleteRole(Role role) throws RanchOperationFailedException;

    /**
     * gets a list of all permissions
     * 
     * @return
     */
    List<Permission> getPermissions();

    /**
     * saves a given {@link Permission}
     * 
     * @param permission
     * @throws MohrValidationException
     *             thrown when the validation of the user fails.
     */
    void savePermision(Permission permission) throws RanchValidationException;

    /**
     * finds users whose username(s) are like the query provided. This means
     * that if a query like 'ct' is provided, all users who begin with the ct
     * characters are returned
     * 
     * @param query
     * @return
     */
    List<User> findUsersByUsername(String query);

    /**
     * gets a user with a given Id
     * 
     * @param userId
     * @return
     */
    User getUserById(String userId);

    /**
     * @param text
     * @return
     */
    Role getRoleById(String text);

    /**
     * finds roles whose name(s) are like the searchString provided. This means
     * that if a search string like 'ct' is provided, all roles whose names
     * begin with ct characters are returned
     * 
     * @param searchString
     * @return
     */
    List<Role> findRolesByName(String searchString);

    /**
     * gets the permission with the given id
     * 
     * @param id
     * @return
     */
    Permission getPermissionById(String id);

    /**
     * gets a list of users on a given page number
     * 
     * @param pageNo
     * @return
     */
    List<User> getUsers(Integer pageNo);

    /**
     * gets a list of roles on a given page number
     * 
     * @param pageNo
     * @return
     */
    List<Role> getRolesByPage(Integer pageNo);

    /**
     * 
     * @return
     */
    int getTotalNumberOfUsers();

    /**
     * gets a list of users that contain a given query in their name
     * 
     * @param query
     * @return searched user
     */
    List<User> searchUserByLoginName(String query);

    /**
     * gets a paged list of users that contain a given query in their name
     * 
     * @param query
     * @param pageNo
     * @return
     */
    List<User> searchUserByLoginName(String query, Integer pageNo);

    /**
     * gets total number of users who meet the search criteria
     * 
     * @param query
     * @return
     */
    int getNumberOfUsersInSearch(String query);
}
